---
title: Invoke job by client id, JSON parameters
summary: Gates a caller-supplied job against the uc4.rules allow/deny list, parsing JSON-encoded parameters before the gate runs, then forwards it to the downstream UC4 scheduling service.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-22
operation_id: OP-004
trigger: A SOAP caller invokes ExecuteJobWithJsonAndClientId on the UC4 route
---

# OP-004: Invoke job by client id, JSON parameters

This process backs the `ExecuteJobWithJsonAndClientId` operation. It follows the same shape as [OP-006](execute-job-with-values-and-client-id.md), the canonical flow, but replaces the positional-value naming step with a JSON-parsing step that runs **before** the allow/deny gate. **Transaction boundary: none.**

| Field | Value |
| --- | --- |
| **Operation ID** | OP-004 |
| **Trigger** | SOAP caller invokes `ExecuteJobWithJsonAndClientId` |
| **Entry operation** | [`ExecuteJobWithJsonAndClientId`](../contracts/uc4-service.md#executejobwithjsonandclientid) |
| **Owning component** | `UC4Service.ExecuteJobWithJsonAndClientId` |
| **Inputs** | `environment` (`short`), `jobName` (`string`), `jsonKeyValuePairs` (`string`) |
| **Outputs** | `UC4Result` — the mapped downstream result, or an empty result if the job is blocked |
| **Failure behavior** | An unhandled exception is surfaced by the WCF framework as a generic SOAP fault carrying full exception detail |

## Request and response

| Direction | Element | Type | Declared in | Notes |
| --- | --- | --- | --- | --- |
| Request | `environment` | `short` | `UC4Service.cs` | Client id identifying the environment |
| Request | `jobName` | `string` | `UC4Service.cs` | The job to invoke |
| Request | `jsonKeyValuePairs` | `string` | `UC4Service.cs` | JSON-encoded key/value parameters, parsed before the gate |
| Response | `<return>` | `UC4Result`* | `UC4Service.cs` | Mapped downstream result, or an empty `UC4Result` if blocked |

## Steps

1. WCF dispatcher activates `UC4Service` as in [OP-006](execute-job-with-values-and-client-id.md#steps).
2. Log the invocation at `INFO` — [BR-UC4-008](../business-rules.md#br-uc4-008-every-invocation-is-traced-at-info).
3. `Enforce.ArgumentNotNull` rejects a null `jobName` — [BR-UC4-004](../business-rules.md#br-uc4-004-job-name-must-not-be-null).
   - On failure: throws → detailed WCF fault.
4. Parse `jsonKeyValuePairs` into a parameter collection — **before** the allow/deny gate runs — [BR-UC4-013](../business-rules.md#br-uc4-013-json-parameters-parsed-before-the-allow-deny-gate).
   - On failure: malformed JSON throws → detailed WCF fault, even for a job the rule set would have blocked.
5. `UC4Service.IsJobAllowed` reads `uc4.rules` and evaluates the gate exactly as in [OP-006 step 4-6](execute-job-with-values-and-client-id.md#steps) — [BR-UC4-001](../business-rules.md#br-uc4-001-job-allowed-by-uc4-rules-document), [BR-UC4-002](../business-rules.md#br-uc4-002-default-allow-for-unmatched-environment), [BR-UC4-003](../business-rules.md#br-uc4-003-rule-evaluation-order-and-match-type).
   - On failure: a missing/malformed rules document or invalid regex throws → detailed WCF fault.*
6. If not allowed: return `new UC4Result()`, discarding the explanatory message — [BR-UC4-005](../business-rules.md#br-uc4-005-blocked-job-returns-empty-result-with-no-explanation). Not a fault.
   - Otherwise: continue to step 7.
7. Resolve the downstream address and stamp the host identity, exactly as in [OP-006 step 9](execute-job-with-values-and-client-id.md#steps) — [BR-UC4-010](../business-rules.md#br-uc4-010-downstream-service-address-resolved-per-call), [BR-UC4-011](../business-rules.md#br-uc4-011-forwarded-job-stamped-with-host-identity).

   > **Origin**: Step 7's downstream client construction is implemented in `SAIF.Web.API.Clients` / `SAIF.Services.UC4` (external packages, not documented by this run) and executed within this operation.*
   - On failure: a missing setting or unreachable address throws → detailed WCF fault.
8. Forward the parsed parameters to the downstream `IUC4Service.ExecuteJob`.
   - On failure: a downstream exception propagates unchanged → detailed WCF fault.
9. Map the downstream result field-by-field onto the published `UC4Result` — [BR-UC4-012](../business-rules.md#br-uc4-012-downstream-result-mapped-field-by-field).
   - On failure: a null downstream result may throw.*
10. WCF dispatcher serializes the `UC4Result` and returns it.

## Process flow

```mermaid
flowchart TD
    A["Activate UC4Service"] --> B["Log invocation<br>at INFO"]
    B --> C["Enforce jobName<br>not null"]
    C -->|"null"| CFAULT["Detailed WCF fault"]
    C --> D["Parse jsonKeyValuePairs"]
    D -->|"malformed JSON"| DFAULT["Detailed WCF fault"]
    D --> E["Read uc4.rules,<br>evaluate gate"]
    E -->|"read/parse fails"| EFAULT["Detailed WCF fault"]
    E --> F{"Allowed?"}
    F -->|"No"| G["Return empty UC4Result<br>message discarded"]
    F -->|"Yes"| H["Resolve downstream address,<br>stamp host identity"]
    H -->|"missing setting"| HFAULT["Detailed WCF fault"]
    H --> I["Forward parsed parameters<br>to downstream service"]
    I -->|"downstream throws"| IFAULT["Detailed WCF fault"]
    I --> J["Map downstream result<br>to published UC4Result"]
    J --> K["Serialize and return"]
    G --> K
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | None |
| Commit point | Not applicable — no persistence |
| Records written | None locally |
| Downstream calls | `UC4Client.ScheduleJob` → downstream UC4 scheduling service |
| Shared state touched | None |
| Repeat-call behavior | Not idempotent from the host's perspective |

## Faults and error handling

| Failure | Fault type the caller receives | Produced by | Source |
| --- | --- | --- | --- |
| `jobName` null | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs` |
| Malformed `jsonKeyValuePairs` | Generic SOAP fault, full exception detail (even for a job that would have been blocked) | The WCF framework | `UC4Service.cs` |
| `uc4.rules` missing/malformed or invalid regex | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs` |
| Downstream construction/call failure | Generic SOAP fault, full exception detail | The WCF framework | `Uc4Client.cs` |

`UC4Service` carries `[LogErrorBehavior]`, an external `IServiceBehavior` whose implementation is not in this repository; its contribution is observability, not fault shaping — see [Faults and error pipeline](../faults.md).

## Authorization

| Requirement | Enforced by | Source | Applies to |
| --- | --- | --- | --- |
| [None in code](../authentication-authorization.md#access-requirements-per-operation) | Nothing — no attribute or programmatic check exists | `UC4Service.cs` | This operation |

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Activation and hosting](../activation-hosting.md)
- [Operations](../operations.md)
- [Faults and error pipeline](../faults.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources
- `src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs`
- `src/WCF/SAIF.Services.WCF.UC4.Host/Uc4Client.cs`